This is an R Markdown!
R markdown is great, and when I say great, I mean REALLY great.
When exporting your markdown you can…
(1) embed figures
(2) view tables
(3) export models
(4) archive your data pipeline
You can write code and execute functions in a similar way to normal R script files. However, there are a few distinct differences between R scripts and R markdown scripts. Some of these differences relate to how code is executed. Other differences can be seen in the added benefit of integrating scripts with outputs and other embedded properties.
The benefit of using markdown with colleagues is they can actually see the script, the figures, the path of model selection, even the assumptions of ANOVA (QQ plots, etc) that normally are hidden behind the curtain. In short, R markdown helps make your science repeatable, sharable, and data analysis coherent!
Here are some common commands and examples of what Markdown can do for you. I reccommend visiting the [R Bookdown for a complete and exhaustive guide](https://bookdown.org/yihui/rmarkdown/ or the R markdown cheat sheet
If you want to test yourself, the R Markdown tutorial is another great guide.
Markdown basics
First: Git with R Projects
My first advise to you would be to set up a GitHub account. Having a GitHub allows you to have all your code, markdown, figures, data, etc archived online for safety and version control. You can make these repositories private or collaborative. It is easy! There are a lot of resources out there on why/how to use GitHub, and you’ll see why it is important as you advance your carpentry–you can read about how painless this is.
Whether you choose to GIT with it, or stick with running from your device, you should start by making an R project in R-Studio. You can read all about how to do this at happygitwithR.com.
In R Studio, clicking the option to make an R project with version control will set you on the path to linking with GitHub (if you go this route, see happygitwithR.com first, as you must set up a github account, then make a repository, then use the repository URL to link to your R project).
If you decide to instead without version control, then set up the project wherever you wish on your computer. When you set your “R Project” directory, R Studio will generate a folder that houses your R Project. From here you can create your Rmd file and folder directory as you wish. For best practices, I recomment setting up a directory for each project (see directory for this project below). From here, everytime you open want to work on this project in R studio, click on the Project. This will allow you to load data in a simple way that anyone can understand (i.e., upload file “symbiont.csv”, from folder “data”)–and it is easy to share this structure with collaborators.
Yet another reason to use R Projects: it will eliminate the pesky and sometimes overly personal directories we all have on our desktop aka: “~/Desktop/PhD/WTFproject/NeverGoingToGetPublished/data.csv”
Figure 1. Data Directory example
Common Commands
Notice the script at the very top of your markdown (this is not standard, but is customized)
output:
html_document:
code_folding: hide
toc: yes
toc_depth: 3
toc_float: yes ***
Let’s go through this line by line…
html_document: an option you originally set when you open the markdown. This is how your file will be exported.
code_folding: hidewill allow you to show or hide all code (option at top of file)
toc: for table of contents on the left
toc_depth: how many header levels you will have in table of contents
toc_float: lets your contents move as you advance in your document.
Play around with these options, and see how they affect your code
There are other options too, such as number_sections: true to add numbering to your sections.
The setup chunk
First, if you want to make a new chunk (where code is written), use the shortcut!
Control + Option + I"will generate a new chunk for your setup: This is your set up code and is a useful way to get around the fact that knitr will look for your .Rmd file and all files in the this directory. By setting the root.dir you can force knitr to look for files in the directory you specify and the folders within.
In the setup chunk (the first code chunk) you can set ‘global’ options, such as message/warning exclusion, or hiding results or outputs.
knitr::opts_chunk$set(warning=FALSE, message=FALSE): This command here is requiring the package knitr in the code chunk (‘set’ for set up) and is saying to “make all warning and message FALSE” i.e., hide them from output.
include=FALSE: this command makes your code absent from final html. It is executed but the code is hidden.eval=FALSE: this command allows you to show the code in your script within R studio, but not evaluate (or run) the code. It is effectively silent in your analysis and output html.echo=FALSE: this will show the output but not the code chunk… notice the difference.results='hide': this will hide all results in a code chunk, or any returned results from your commands.collapse = TRUE: this is one of my new favorites. You enter this to your chunk options for a code chunk to run all the way through and not separate into pieces of results. This is usueful if you have lots of outputs (even if they are hidden usingresults='hide', the code chunk will still give breaks where results would be. Collapse = TRUE stops this.)
Text formatting
It is useful to understand how to modify text and format headings. You can do this in a variety of ways.
line break: this is executed by two spaces at the end of previous line, and a returnheadings: use#for headings,#….####and so on. # is largest and #### smallest heading
Italics comes from two calls italics or italics; bold is done the same way bold and bold
Superscriptsuperscript2 orstrikethroughsstrikethroughcan also be useful text modifiers.add linksto urls like this R studio linkendash: –
emdash: —
ellipsis: …inline equation: \(A = \pi*r^{2}\) or \(y = a*x+ b\)(a line can inserted with
***)using the
>before and after a line can give you a quote/emphasis, such as…
“Its Van Halen, not Van Hagar!”
- Garth Algar
Code chunks
Code chunks are where your code is executed. If you do not set the working directory in setup each code chunk will revert to its original directory, or where your .Rmd file lives. This is one more reason why you should run everything out of your R Project.
## love your data and it will love you back
getwd() #where are your files? See how they should all be running from your R project in the directory## [1] "/Users/chriswall/Desktop/Research and Teaching/github/Intro to Markdown"Below: This is a code chunk, and this is how you enter your data into R markdown. Note the code chunks always start with a ```{r...} and ends with a {...}. You can add these chunks with the shortcut Control + Option + I".
The code chunk below is an example of attaching the data (.csv), familiar to you R-heads. Since the data file is in the directory specified by knitr::opts_knit$set(root.dir =... above, you can reference the .csv easily.
################################################
# import data, observe structure
################################################
# data file is in the folder 'data', within main working directory
data<-read.csv("data/coral_data.csv")
names(data)## [1] "Time.point" "Period" "Site" "Species" "Status"
## [6] "Sample.ID" "Pair" "Depth.ft" "biomass" "chla"Including figures
You can include figures from script output as results, or figures from files in your directory. First, let’s see how you can add an image from a file to your markdown.
